OpenEdge Development: <br />Web Services Using the sample PscObjectIDHandler and HandlerControlBlock classes

Axis is a JAX-RPC-based Web service toolkit. JAX-RPC-based Web Service toolkits provide the ability to examine, modify, and insert information into SOAP requests using handler objects that conform to a defined interface (javax.xml.rpc.handler.GenericHandler). Axis client interface classes do not give programmatic access to SOAP request and response headers; therefore a client application must create and use one of these handlers to access these SOAP message headers.

A client application defines one or more of these handlers and binds them to a <portType> (Open Client object) defined in the Web service's WSDL document. Each time a SOAP request or response message is handled by an object, the appropriate handlers bound to the object are called and allowed access to the request or response message. For more information, see the source code modules for the Java samples described in Chapter 6, " Sample Progress 4GL Web Services and Client Applications."

OpenEdge provides a sample handler class (PscObjectIDHandler) to manage object IDs. This PscObjectIDHandler class is one possible implementation of a JAX-RPC handler. It provides two essential pieces of functionality:

It is invoked for each incoming SOAP response for the <portType> element (Open Client object type) where it is bound. When invoked, it scans the SOAP response header for an object ID that corresponds to an Open Client object name. If it finds one of these Open Client object IDs, it extracts the object ID value and stores it along with the object name. The client application or the handler can then access this stored object ID to insert it into a subsequent SOAP request header. If a handler does not already have an object ID value reserved to insert in a given SOAP request header, it automatically uses the first object ID that it stores.

It is invoked for each outgoing SOAP request for the <portType> element (Open Client object type) where it is bound. It then inserts a SOAP header containing the object ID for the Open Client object name that corresponds to the <portType> element where it is bound. If an object ID value does not exist for the Open Client object name, the handler does not insert a SOAP header into the request.

Along with the PscObjectIDHandler class provided with the Progress 4GL Web services samples is a companion class, HandlerControlBlock. This class allows the Web service client application to access object ID values stored in a PscObjectIDHandler object. It also gives the application the ability to control the Object ID value the PscObjectIDHandler inserts into SOAP request headers. For each PscObjectIDHandler object instance, there is a companion HandlerControlBlock created and associated with it.